/*
 * AscTextReader.java
 *
 * Created on August 27, 2002, 12:34 PM
 *
 * Copyright (c) 2002 The General Electric Company
 */

package com.ge.healthcare.autosc.common.util.dataItem;

import com.ge.healthcare.autosc.common.exceptions.BasicException;

/**
 * Reader interface for reading a text data stream one line at a time.
 *  Objects implementing this interface are used in a manner similar to
 *  java.io.BufferedReader, except that the interface only defines three
 *  methods, readLine(), close(), and silentlyClose() and they throw
 *  AscServiceAbortException instead of IOException.
 * Implementors of this interface are responsible for buffering the
 *  reader.
 *
 * @author Daniel S. Horwitz, Compuware Corp.
 *
 * @version AutoSC P5P6
 */
public interface IASCTextReader
{
    /**
     * Close the reader.
     *
     * @exception AscServiceAbortException If an error is detected closing
     *  the reader, an error is logged and then an abort exception is thrown.
     */
    void close() throws BasicException;

    /**
     * Silently close the reader.  This never throws an exception.  If
     *  an I/O error is detected closing a stream, it is not logged.
     *  Other errors may be logged at the discretion of the implementor.
     */
    void silentlyClose();

    /**
     * Read a line of text.  If the text is read from an underlying reader,
     *  a line is considered to be terminated by any one of a line feed,
     *  a carriage return, or a carriage return followed immediately by
     *  a linefeed.  Text lines can also be constructed by the reader, in
     *  which case the reader defines a text line.  Typically, a text line
     *  is a record from an underlying data source.
     *
     * @return A string containing the contents of the line, not including any
     *   line-termination characters, or null if the end of the data has
     *   been reached.
     *
     * @exception AscServiceAbortException If an error is detected reading
     *  a line of text, an error is logged and then an abort exception is
     *  thrown.
     */
    String readLine() throws BasicException;
}
